﻿Intel(R) Trusted Device Setup - Seal Validation Tool 1.0.6.2

This document describes usage of Intel(R) TDS Seal Validation Tool
==================================================================

Intel® Trusted Device Setup Seal Validation Tool allows to perform a local attestation
 of Intel(R) TDS system components for functional validation purposes.
It is envisioned that the production components (OS Health Attestation Service and its
 on-device agent) would perform similar assertions of platform state, though instead of
 local attestation, a remote attestation (including TPM Quote verification) would be
 done by those tools.
See section 3.3 for list of assertions the Intel® TDS Validation Tool is doing

==================================================================
Table of Contents:

1.  Package content
2.  System requirements
3.  Intel(R) TDS Seal Validation Tool Configuration
4.  Intel(R) TDS Seal Validation Tool Capabilities
 4.1.  Validating state of the device
 4.2.  Unsealing the device
 4.3.  Comparing TPM logs
5.  Logging options
6. Intel(R) TDS Seal Validation Tool Features description
 6.1.  Verification of the PMF certificate
 6.2.  Verification of the disk measurements
7.  Return codes

==================================================================

1. Package content
------------------

This Intel Trusted Device Setup Sealing package contains following files:
* svt.exe - Command line application
* svt.ini - Reference INI configuration file
* Intel_TDS_Seal_Validation_Readme.txt - This document

2. System requirements
----------------------
The Intel(R) TDS Seal Validation Tool needs to be run an Intel(R) TDS-enabled platform
equipped with a TPM. Refer to Intel(R) TDS EndToEnd flow document for platform-level
requirements.

OS Requirements: Windows 10 (64-bit) with Intel(R) Management Engine Interface driver
                 (HECI driver) installed
The tool needs to be run as Administrator.

SAS: Intel(R) TDS System Architecture Spec 0.95
IFWI: WW35'19-WHL
Platform Measurements Tool (PMT): 2.11B
Trusted Device Setup: 0.1, 1.0

3. Intel(R) TDS Seal Validation Tool Configuration
---------------------------------------------

Intel(R) TDS Validation Tool behaviour can be configured from INI configuration file.
Each configuration parameter has to be declared under specific section.
If parameter is applicable and it is not specified in INI configuration file, a default value will be applied.
Configuration file contains the following options for configuring the requested validation parameters:

* Section [Expected Seal Configuration]:
  - ChassisIntrusionEnabled = 1 (Enabled) or 0 (Disabled) | Default value: 0
  - BIOSLockEnabled = 1 (Enabled) or 0 (Disabled) | Default value: 0
  - SealSigningEnabled = 1 (Enabled) or 0 (Disabled) | Default value: 0
  - CustomOptOutEnabled = 1 (Enabled) or 0 (Disabled) | Default value: 0
  - SEDLockEnabled = 1 (Enabled) or 0 (Disabled) | Default value: 0
  - PMFSigningEnabled = 1 (Enabled) or 0 (Disabled) | Default value: 0
 
* Section [Expected Intel TDS Feature configuration]:
  - BootGuardEnabled = 1 (Enabled) or 0 (Disabled) | Default value: 0
    Expect Boot Guard profile 5 to be enabled

* Section [Logging]:
  - FileLogPath = svt.log | Default value: svt.log
    Path to log file containing logging information. Path may be absolute or relative to working directory of svt.exe process.
  - FileLogLevel = 0 (OFF), 1 (BRIEF), 2 (INFO), 3 (DEBUG) | Default value: 3
  
* Section [Device Identification]:
  - DeviceIdSource = UUID, SERIAL_NUMBER, OEM_DEFINED_BLOB, OEM_DEFINED_LITERAL
    Default: UUID
	Source of the Device ID. Options supported by this release:
		> UUID - Device ID is obtained from SMBIOS System Information UUID field.
		> SERIAL_NUMBER - Device ID is obtained from SMBIOS System Information Serial Number field.
		> OEM_DEFINED_BLOB - Requires --external_device_id <string> option. Uppercase hex string starting with 0x. Max length: 32 bytes.
		> OEM_DEFINED_LITERAL - Requires --external_device_id <string> option. Max length: 31 bytes. String must not start with 0x to avoid confusion with blob option. 

* Section [PMF Signature Validation]:
  NOTE: This section applies only if PMFSigningEnabled==1 in set the Seal.
  - TrustedCaDir = <path_to_trusted_ca_dir>
    A directory of trusted certificates.
  - IntermediateCaDir = <path_to_intermediate_ca_dir>
    A directory of intermediate certificates. Additional untrusted certificates (intermediate issuer CAs)
    used to construct a certificate chain from the subject certificate to a trust-anchor.

* Section [Seal Signature Validation]:
  NOTE: This section applies only if SealSigningEnabled==1 in the [SealConfiguration] section.
  - ExpectedSealSigningAlgorithm = SHA256-NULL-ENCRYPTION | SHA256-RSA-2048-PKCS1
    Algorithm used to seal signing.
  - TL3SealIdentityVerificationFile = <path_to_tl3_identity_verification_file> | No default value, parameter must be defined when ExpectedSealSigningAlgorithm is SHA256-NULL-ENCRYPTION.
    Path to CSV file containing TL3 output that allows to verify seal identity. Path may contain tokens for values distinguished by Device Identification.
    DeviceIdSource tokens are delimited by double-colons (e.g. TDS_TL3_Seal_Identity_File_::SERIAL_NUMBER::.csv). For list of supported tokens see section [Device Identification] description.
    OEM_DEFINED values requires providing a value for external_device_id. Two different types of OEM_DEFINED DeviceIdSources cannot be used at once.
    Path may be absolute or relative to working directory of svt.exe process.

* Section [Expected CustomOptOut]:
  NOTE: This section applies only if CustomOptOutEnabled==1 in the [SealConfiguration] section.
  - OptOutHotKey = <hotkey> | No default value, parameter must be defined.
    Custom Opt-out key sequence allowing to break the DropShip boot. Number of keystrokes in the range 1-7.
  - OptOutIntervalSeconds = <15;2^32-1> | Default value: 15
    Time in seconds during which the Drop Ship BIOS Extension shall wait for the hotkey to be inserted.

4. Intel(R) TDS Seal Validation Tool Capabilities
-------------------------------------------------

4.1. Validating the device
--------------------------

To validate the device, use:
> svt.exe --validate [--skip_retrieving_pcrs] [--skip_retrieving_tpm_event_log] [--skip_retrieving_platform_measurements]
                     [--tpm_event_log_file=<tpm_event_log_file>] [-c <ini_config_file>] [-o <log_file>] [-v <0-3>] [-l <0-3>]
                     [-g <pmf>] [--pmf_external_certificate_path=<pmf_external_certificate_path>] [--reference_tpm_log_file=<reference_tpm_log_file>] 
                     [--bypass_version_check] [--external_device_id=<string>] [--tl3_seal_identity_verification_file=<TL3_seal_identity_verification_file>]

Required Options:
      --validate                                validate the device

Optional options:
      --skip_retrieving_pcrs                    skip "Retrieve PCRs from TPM" stage
      --skip_retrieving_tpm_event_log           skip "Retrieve TPM Event Log" stage
      --skip_retrieving_platform_measurements   skip "Retrieve Platform Measurements" stage
      --skip_btg_validation                     skip "Boot Guard validation" stage
      --tpm_event_log_file=<tpm_event_log_file> load TPM Event log from file										
  -c  <ini_config_file>                         reference seal configuration file
  -o  <log_file>                                path to log file
  -v  <0-3>                                     run in verbose mode. 0 - OFF, 1 - BRIEF, 2 - INFO, 3 - DEBUG
  -l  <0-3>                                     file logging level. 0 - OFF, 1 - BRIEF, 2 - INFO, 3 - DEBUG
  -g  <pmf>                                     load Platform Measurements from file instead of
                                                loading it from CSME
      --pmf_external_certificate_path=<pmf_external_certificate_path> 
                                                path to the external PMF Certificate
      --reference_tpm_log_file=<reference_tpm_log_file>
                                                path to the reference TPM Log
      --bypass_version_check                    skip checking if Intel(R) TDS version on the platform 
                                                is supported by this tool
      --external_device_id=<string>             provide Device ID as ASCII literal or hex string 
                                                starting with 0x.			
      --tl3_seal_identity_verification_file=<TL3_seal_identity_verification_file>
                                                path to the Trusted Level 3 seal identity verification file	
                                                
Unicode characters will be converted to nearest ASCII.

During the validation Intel(R) TDS Seal Validation Tool executes following steps:
* Check if Intel(R) Trusted Device Setup feature is enabled on the platform and has supported version
* Retrieve Feature State and Tamperproof Seal Log from CSME using FEATURE_GET_STATE command
* Retrieve PCR values from TPM
* Retrieve TPM Event Log from system
  - Optionally the TPM Event Log can be loaded from file instead of the system
* Retrieve Platform Measurements File (PMF) from CSME
  - Optionally the PMF can be loaded from file instead of the CSME
  - Verify Platform Measurements File structure (including reserved fields)
* Retrieve platform information from SMBIOS and Windows Registry.
* Check that the device is sealed and tamperproof Seal is intact
* Check if the re-calculated PCR values from TPM Event Log match the PCR values from TPM (Local TPM Attestation)
  - Note for remote attestation scenarios, a signed TPM Quote would be used instead of the raw PCRs
* [Optional] If Reference TPM Log is provided (via --reference_tpm_log_file parameter), compare it with the TPM Log on the Device (referred to as: 'Live TPM Log')
* Ensure Sealing Log is bound to the platform by asserting its hash was properly measured to PCR#5
* Check if the Platform Measurements File retrieved in previous step is bound to the platform by asserting its hash matches a value in the Sealing Log
* Check if Platform Measurements File signature is valid.
* Check if Platform Measurements File certificate is trustworthy.
* Check if Seal Signature is trustworthy 
  - When TL1 Seal Signing is enabled: 
    > validate if the Seal Data matches the platform
    > validate if the signing key is whitelisted in the PMF
  - When TL3 Seal Signing is enabled: 
    > validate if the Seal Data matches actual platform
    > validate if the TL3 Seal Identity Verification Data mathces the platform 
* Compare if PCR values from Platform Measurements File matches the values retrieved from TPM
* Compare if Disk Measurements extended to PCR#5 match the Platform Measurements File
  - this release of the tool only checks if the actual disk layout matches the EFI_GPT_EVENT
* Check if disk partition measurements are integral
  - assert the per-partition disk measurements (e.g. BOM file)
* Check if actual Seal Configuration from the FEATURE_GET_STATE matches the expectation:
  - compare with the Expected Seal Configuration from the Seal Validation Tool configuration file
  - compare with the Seal Configuration from the PMF.
  - validate that the seal configuration was properly extended to PCR[5]
* Check if platform information matches the platform
  - compare SMBIOS and Registry data from the platform 
  - check that PMF has not expired
  - check that Device ID from the Seal Log matches the actual platform
* Compare if Disk Lock Events from Seal Log match to the Seal configuration  
* Check if TPM event log is valid against Boot Guard configuration on the platform. 

4.2. Unsealing the device
-------------------------
It is envisioned that an actual OS Device Provisioning & Attestation Agent would disable the Intel(R) TDS feature for subsequent boots, after the device is successfully onboarded to an IT environment. In order to allow simulating this behavior, the Intel(R) TDS Seal Validation Tool features an ‘unseal’ mode capable of disabling Intel(R) TDS Seal.
Since this tool is meant to assist in functional validation and not implement a full provisioning service’s behavior (which is envisioned to automatically disable TDS), this action needs to be manually triggered by user.

To unseal the device, use:
 > svt.exe --unseal [-r <0-2>] [-c <ini_config_file>] [-o <log_file>] [-v <0-3>] [-l <0-3>] [--bypass_version_check]

Required Options:
      --unseal                              unseal the device

Optional Options:
  -r, --reason=<0-2>                        unseal reason
                                            0 - Attestation Successful
                                            1 - Attestation Failed
                                            2 - Seal Aborted (Default)
  -c  <ini_config_file>                     reference seal configuration file
  -o  <log_file>                            path to log file
  -v  <0-3>                                 run in verbose mode. 0 - OFF, 1 - BRIEF, 2 - INFO, 3 - DEBUG
  -l  <0-3>                                 file logging level. 0 - OFF, 1 - BRIEF, 2 - INFO, 3 - DEBUG
      --bypass_version_check                skip checking if Intel(R) TDS version on the platform 
                                            is supported by this tool

Unicode characters will be converted to nearest ASCII.

4.3. Comparing TPM logs
-----------------------
The SVT tool provides a separate mode of operation, allowing to compare the platform's TPM Log File (Live TPM Log) with a Reference TPM Log supplied by the user.
Note: This mode can also be run on a non-TDS-compatible device (does not require CSME connectivity).
By default, the Live TPM Log is retrieved from the last boot of the device (TPM 2.0 and TPM Base Services support in the operating system are required).
This behavior can be overriden using the "--tpm_event_log_file" command-line option, which allows to specify an external file to use as the Live TPM Log (TPM 2.0 and TPM Base Services support are not required in such case).
By default all PCRs are being compared, but the log comparision mode allows to specify which PCRs will be taken for comparison with "--compared_pcrs" flag.

To compare TPM logs, use:
> svt.exe --compare_log --reference_tpm_log_file=<reference_tpm_log_file> [--tpm_event_log_file=<tpm_event_log_file>] [--compared_pcrs=<0-23>,[<0-23>,...]] [-c <ini_config_file>] [-o <log_file>] [-v <0-3>] [-l <0-3>]

Required Options:
      --compare_log         compare reference TPM log to live TPM log
      --reference_tpm_log_file=<reference_tpm_log_file>
                            path to the reference TPM Log

Optional Options:
      --tpm_event_log_file=<tpm_event_log_file>
                            path to the live TPM Log, if not specified TPM log
                            will be retrieved from a system
      --compared_pcrs=<0-23>,[<0-23>,...]
                            comma-separated list of Integers in range <0-23>, e
                            .g. --compared_pcrs=1,4,8,23. If flag is not provid
                            ed, all PCRs will be compared
  -c <ini_config_file>      path to the Seal Validation Tool Configuration file
  -o <log_file>             path to log file
  -v <0-3>                  cli logging level. 0 - OFF, 1 - BRIEF, 2 - INFO, 3 - DEBUG
  -l <0-3>                  file logging level. 0 - OFF, 1 - BRIEF, 2 - INFO, 3 - DEBUG

Unicode characters will be converted to nearest ASCII.

If differences are found between the two logs, a report will be printed on the screen.
There are 3 types of errors and 2 types of warnings that may occur during TPM Log comparison
* PCR digest mismatch error - corresponding extending events have different digests.
  This results in intermediate PCR value mismatch after processing those events.
* Mismatched extending event error - one of TPM Logs contain extending event that is not present in opposite TPM Log (because it does not contain more events).
  This results in intermediate PCR value mismatch after processing this event.
* Initial PCR Mismatch error - Initial PCR values are different because of an event that affected initial PCR value.
* Mismatched non-extending event warning - one of the TPM Logs contains a non-extending event that is not present in opposite TPM Log.
  Because event is non-extending, intermediate PCR value will not change.
* Event type mismatch warning - opposite extending events have same digests but different types.
Below is a sample single event printout where:
* EVENT_SOURCE can take following values:
  - Actual event (Live Log) - if event is from the Live Log
  - Expected event (Reference Log) - if event is from the Reference Log
  - Mismatched event (Live Log) - if event is from the Live Log, it is an information (non-extending) event and has no counterpart event in the Reference Log
  - Mismatched event (Reference Log) - if event is from the Reference Log, it is an information (non-extending) event and has no counterpart event in the Live Log
* X is equal to an event position in a PCR and Y is equal to the number of events in this PCR (not counting Specification ID Version Event)
  - 1 <= X <= Y for regular events
  - X = 0 for initial PCR value event
  - X = - for a missing event
* EVENT_TYPE is:
  - event_value_as_8_hex_bytes(event_name) - for regular events
  - N/A (PCR initial value) - for initial PCR value event
  - N/A (no more events) - for missing event
* Event data is truncated to 408 bytes. Appropriate information about the occurrence of truncation is printed.
* Z is an index of PCR which the event belongs to.

 EVENT_SOURCE [X/Y]:
   Type:                      EVENT_TYPE
   SHA256 Digest:             0000000000000000000000000000000000000000000000000000000000000000
   Intermediate PCR[Z] Value: 0000000000000000000000000000000000000000000000000000000000000003
   Data (17 bytes):
     00000000 | 7878 7878 7878 7878 7878 7878 7878 7878 7878                 | xxxxxxxxxxxxxxxxxx

5. Logging options
----------------------------

Logging options can be set in configuration file, or by setting options in command line, if not set by any of these methods
Intel(R) TDS Seal Validation Tool uses default values.

Logging options priority:
  Options set in command line have the highest priority, second to them are options set in configuration file, default
  options have the lowest priority.

Command line options:
  Logging verbosity level on command line can be set by the use of -v option with a value from range 0-3.
  File logging options allow to set log file path by the use of -o option and to set log file logging verbosity level
  by setting the -l option with a value from range 0-3.

Configuration file options:
  Configuration file does not contain any option to set command line verbosity level.
  File logging section contains options that allow to set log file path under FileLogPath option and to set log file
  logging verbosity level under FileLogLevel with a value from range 0-3.

Available verbosity values:
  Command line verbosity levels: OFF, BRIEF, INFO, DEBUG.
  Log file verbosity levels: OFF, BRIEF, INFO, DEBUG.

Defaut values:
  Command line verbosity level: INFO
  Log file verbosity level: DEBUG

Remarks:
  If file logging verbosity level is set to OFF, then the log file will not be created.


6. Intel(R) TDS Seal Validation Tool Features description

----------------------------------------
6.1. Verification of the PMF certificate
----------------------------------------

A directory of trusted and intermediate certificates should contain certificates in PEM format. The path to
the directory with certificates should end only with the name of the folder without any additional characters
e.g. C:\user\trustedCA or C:\user\intermediateCA. All certificates must have the .crt extension e.g. rootCA.crt

6.2.  Verification of the disk measurements
----------------------------------------
Disk measurement types supported in this release of the tool:
- BOM_PROVIDED(3)

6.2.1 Verification of the BOM_PROVIDED(3) measurement
----------------------------------------
For each partition in the PMF that has BOM_PROVIDED(3) measurement type specified, the Intel(R) TDS Seal Validation Tool checks that the hash of BOM file provided
in the PMF matches the digest of the file on disk. Semantics of the BOM file are not checked - this is an OEM-specific step which depends on the actual BOM contents
and the OEM implementation of the measurement.

The Intel(R) TDS Seal Validation Tool additionally checks that the BOM file path is absolute and located on the partition being measured(*).

(*) Intel(R) TDS Seal Validation Tool will check if the volume letter in the path matches the volume indicated by the LBA range.
       
Known limitation:
In the current version, the partition being measured must be assigned to a volume letter in order to retrieve BOM file from it.

7. Return codes
-----------------

Intel(R) TDS Seal Validation Tool exits with following return codes:
-  RC_SUCCESS                  (0) -> Returned when finished with success.
-  RC_HECI_COMMUNICATION_ERROR (2) -> Returned when HECI communication failed.
-  RC_INVALID_PARAMETERS       (3) -> Returned when invalid parameters were passed to the tool (including wrong CLI input,
                                      errors during parsing Platform Measuerment file or invalid INI configuration).
-  RC_WRONG_STATE              (4) -> Returned if the device is sealed when sealing or unsealed when unsealing.
-  RC_VALIDATION_ERROR         (5) -> Returned when comparison failed. 
-  RC_INTERNAL_ERROR           (1) -> Returned when unexpected error occurred.
-  RC_GENERIC_ERROR            (8) -> Returned when an error occurred that is hard to classify. Error description is stored in log file.

-  RC_VERSION_ERROR            (6) -> Returned when Intel(R) TDS version is not supported.
-  RC_NOT_SUPPORTED            (7) -> Returned when hardware setup is not supported.
